Continuing the review in 2m ;)

Sharing my mental model after our live session going through these PR comments with the reasoning why.

flowchart LR
    Verbose[Start verbose] --> Cut[Keep the meaning, not the length] --> Cues[Use formats and visual to your advantage] --> Tenets[Remember our progressive tenet and our global audience]

1. Start verbose like you did - explain as much as possible without worrying whether is too much or not. It's easier to edit with as much context than without context.
2. Try cutting words that when removed don't change the message you want to convey. For example, in your codebase, underlying directory structure of the Powertools for AWS Lambda (TypeScript).
3. Use synonyms to vary your vocabulary, including shorter ones to reduce sentence length.
4. Make use of new paragraphs when you have multiple points to make. If context is needed for each key point, try using bullet points - key point. followed by context.
5. Try different text formats and markdown elements to make your information more easily digestible. For example, use tables when enumerating breaking changes.
6. Use visual cues like diagrams and anners (sparingly) to bring key information upfront like whether to continue reading or not.
7. Use code annotation for code lines that could use additional context with rich text _(links, etc.).

Last but not least, rely on these for judgement when to accept suggestions or continue editing it:

1. Progressive tenet. Treat our docs like a product that is always becoming. We don't need to provide every piece of information upfront, since no one has such large working memory. Apply the progressive tenet so there is something for everyone - from beginners to advanced to heroes (80/20%).
2. Global English. We have a global audience with the vast majority not being native English speakers. Use shorter sentences, simplify your vocabulary where needed, and avoid the temptation of deferring a short explanation to yet another link (e.g., tab hell).
3. Limit reviews. Write verbose, edit yourself, then seek review from a limited number of people (1, 2 max in our context). Rely on our tenets, global English, and your gut by putting yourself in the customers shoes -- is this easy to grasp and enough for me to get going OR do I need to block my time do digest what I need to be productive?

Hope that helps <3

Quality Gate passed

Issues
0 New issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

Reviewing the last changes :)